home *** CD-ROM | disk | FTP | other *** search
/ Linux Cubed Series 3: Developer Tools / Linux Cubed Series 3 - Developer Tools.iso / devel / db / esm-3.1 / esm-3 / usr / local / sm / doc / install.ascii < prev    next >
Encoding:
Text File  |  1996-05-05  |  14.7 KB  |  397 lines
  1.  
  2.  
  3.  
  4. Installation(1)     UNIX Programmer's Manual      Installation(1)
  5.  
  6.  
  7.  
  8. NAME
  9.      Installation - EXODUS Storage Manager 3.1 Installation
  10.      Manual
  11.  
  12. DESCRIPTION
  13.      This document tells how to get a copy of the EXODUS Storage
  14.      Manager source and install it on your system.
  15.  
  16. GETTING THE SOFTWARE
  17.      The Exodus Storage Manager is available without charge by
  18.      anonymous FTP from ftp.cs.wisc.edu.  All of the Exodus
  19.      software is located in the exodus directory.  The Storage
  20.      Manager sources, documentation, and test programs are avail-
  21.      able in: sm/sm.src.3.1.tar.Z
  22.  
  23.      To eliminate the need to compile the Storage Manager, we
  24.      provide libraries for SPARCstations/SUN-OS, HP 7xx/HP-UX,
  25.      and DECstations/ULTRIX in sm.sparc.3.1.tar.Z,
  26.      sm.hp.3.1.tar.Z and sm.dec.3.1.tar.Z, respectively. The
  27.      instructions below describe how to un-tar the release and
  28.      install the Storage Manager by building binaries from the
  29.      libraries provided. We also include instructions for compil-
  30.      ing the Storage Manager for those who wish to do so.
  31.  
  32. PREREQUISITES
  33.      The Storage Manager uses System V shared memory and sema-
  34.      phores, so your kernel must have them installed.  The kernel
  35.      should support a shared memory segment of at least 4 mega-
  36.      bytes.  If you do not know if your system is configured with
  37.      shared memory, see your system administrator.  If you try to
  38.      run the  Storage Manager server on a system that does not
  39.      have shared memory, the server will print an extensive mes-
  40.      sage about its failure to allocate shared memory, and it
  41.      will tell you how much shared memory it was trying to
  42.      acquire;  then it will exit.  The amount of shared memory
  43.      needed is based on the server buffer pool size option called
  44.      bufpages.  See the user guide for instructions on setting
  45.      options.
  46.  
  47.      The Storage Manager is written in C++, and is made with GNU
  48.      C++ (g++ version 2.4.5 (we have also made it with 2.3.3 in
  49.      the past)), so g++ must be available on your system to
  50.      install the SM.  The Storage Manager's client application
  51.      library has a C interface, so applications can be written in
  52.      C or C++.  If you wish to use the client library
  53.      (libsm_client.a) we provide, you must link applications with
  54.      g++ (or eg++, the Exodus E compiler, an extension of g++).
  55.  
  56.      Because the include files for the various C++ compilers
  57.      differ, and in many cases are site-dependent, you may
  58.      encounter some compilation problems due to differences in
  59.      include files and their locations. These can usually be
  60.  
  61.  
  62.  
  63. Printed 11/9/93                                                 1
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. Installation(1)     UNIX Programmer's Manual      Installation(1)
  71.  
  72.  
  73.  
  74.      resolved with minor changes to the code.  If you have prob-
  75.      lems with compiling because certain system include files
  76.      cannot be found, see your system administrator.  Some system
  77.      include files (particularly network-related ones) are not
  78.      included with the standard compiler and library releases,
  79.      and your system administrator might have to install them for
  80.      you.
  81.  
  82. DISK REQUIREMENTS
  83.      The compressed tar file for the source release
  84.      (sm.src.3.1.tar.Z) is about 2.5 megabytes.  The uncompressed
  85.      tar file for the source release (sm.src.3.1.tar) is about
  86.      8.4 megabytes.
  87.  
  88.      The table below lists the minimum disk requirements for mak-
  89.      ing a Storage Manager (compilation and linking), and for the
  90.      installed files.  It includes the doc/ and tests/ direc-
  91.      tories.  These figures are approximate.
  92.  
  93.    Architecture      everything installed but tests   binaries & libraries only
  94. _______________________________________________________________________________
  95. MIPS (DECstations)           13 Megabytes                   3.2 Megabytes
  96.   SPARCstations              11.5 Megabytes                 2.5 Megabytes
  97.      HP 7xx                  24 Megabytes                   5.7 Megabytes
  98.  
  99. PRELIMINARIES
  100.      If the Storage Manager is to be used by multiple users, we
  101.      recommend (but do not require) creating a user and account
  102.      for the Storage Manager.  For the purpose of this discus-
  103.      sion, we call the account exodus, but you can give it any
  104.      name you please. All files created by the Storage Manager's
  105.      volume formatting program will be owned by the user who runs
  106.      it and will be given permission bits 0604 (user read and
  107.      write permissions, public read permission). If raw disk par-
  108.      titions are to be used with  the Storage Manager, they must
  109.      be mounted so that the Storage Manager can read and write
  110.      them.
  111.  
  112.      Normally, the Storage Manager listens on a port, named in
  113.      /etc/services, for client messages. The default name of this
  114.      port is "exodussm". Clients, by default, also look up this
  115.      port in /etc/services. Therefore, we suggest installing in
  116.      /etc/services an entry such as:
  117.  
  118.           exodussm  1152/tcp     #exodus Storage Manager
  119.  
  120.      Note: You do not need to install this port name now.  The SM
  121.      can run without it as long as certain options are set
  122.      correctly.  The examples in the tests/ directory show how to
  123.      set these options.  More information on /etc/services can be
  124.      found by reading "man services".  More information on the
  125.      server's port usage, including alternative ports, can be
  126.  
  127.  
  128.  
  129. Printed 11/9/93                                                 2
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. Installation(1)     UNIX Programmer's Manual      Installation(1)
  137.  
  138.  
  139.  
  140.      found in section 5.2 of the user guide.
  141.  
  142. INSTALLING THE STORAGE MANAGER
  143.      Create    the directory in which to un-tar the release.  For
  144.                the purpose of this discussion, call it SMROOT.
  145.  
  146.      Extract   the sources from the tar file.  Perhaps you
  147.                haven't got enough disk space on one disk to put
  148.                both the source tar file and the extracted sources
  149.                in the same directory, so we assume that you put
  150.                the tar file in /tmp:
  151.  
  152.                     cd SMROOT
  153.                     zcat /tmp/sm.src.3.1.tar.Z | tar -xvf -
  154.  
  155.  
  156.                The source release contains the following direc-
  157.                tories: src, doc, tests, include, lib, and bin.
  158.                The src directory contains the Storage Manager
  159.                source code. The doc directory contains documenta-
  160.                tion on installing and using the Storage Manager.
  161.                The tests directory contains test and example pro-
  162.                grams. The include, lib and bin directories are
  163.                shell directories in the source release.  After
  164.                you install an object release (from
  165.                sm.<machine>.3.1.tar.Z), the include directory
  166.                will contain an include file that your applica-
  167.                tions use, the lib directory will contain the
  168.                libraries from which you built your executables,
  169.                The doc and tests directories contain "README"
  170.                files that give information about their contents.
  171.  
  172.                The libraries we distribute are not complete
  173.                because there are configuration options and extra
  174.                functions that some users may wish to include. The
  175.                client library (libsm_client.a), and the server
  176.                (sm_server) must be built from the libraries con-
  177.                tained in the release.  There are four steps to
  178.                install the libraries and build the binaries.  The
  179.                first is to un-tar the object release file:
  180.  
  181.                     cd SMROOT
  182.                     zcat /tmp/sm.<machine>.3.1.tar.Z | tar -xvf -
  183.  
  184.  
  185.                The second step is to edit the file
  186.                SMROOT/src/config/configOptions.c to indicate the
  187.                location of your site's default configuration
  188.                files and the location of the disk I/O program
  189.                used by the server.  See the comments in
  190.                configOptions.c for instructions on what to
  191.                change.  As you learn more about the Storage
  192.  
  193.  
  194.  
  195. Printed 11/9/93                                                 3
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. Installation(1)     UNIX Programmer's Manual      Installation(1)
  203.  
  204.  
  205.  
  206.                Manager, you may wish to establish a configuration
  207.                file that is used by everyone at your site. If so,
  208.                src/config/configOptions.c will need to be updated
  209.                and the final step (below) repeated.
  210.  
  211.                The third step is to set up a few things for your
  212.                compiler.  If your C++ compiler is not called
  213.                "g++" you need to change src/makefile.options to
  214.                use the proper names. The variables to change are
  215.                CC and CPLUSPLUS located at the bottom of the
  216.                file. The system can also be installed with the E
  217.                compiler we distribute.  By default, the E com-
  218.                piler attempts to link in libsm_client.a (since E
  219.                programs usually require persistence), but this
  220.                can cause problems at the link stage of installing
  221.                or compiling the Storage Manager. Before using E
  222.                for this purpose, you need to set an environment
  223.                variable as follows:
  224.  
  225.                     setenv SM_CLIENT_LIB
  226.  
  227.  
  228.                Once the compiler issues have been settled, the
  229.                fourth and final step is to make the binaries:
  230.  
  231.                     cd SMROOT/src
  232.                     make binary_install
  233.  
  234.  
  235.                This will generate bin/sm_server and
  236.                lib/libsm_client.a.  Note, you may see warnings
  237.                from "make" concerning "multiple rules" or "too
  238.                many command lines".  These messages can be
  239.                ignored.
  240.  
  241.                The user guide, "Using the EXODUS Storage
  242.                Manager," refers to this installation guide for
  243.                the locations of the files needed to run the
  244.                Storage Manager. Here is the list of files and
  245.                their location in the release:
  246.  
  247.                     libsm_client.a:   SMROOT/lib
  248.                     sm_client.h:                   SMROOT/include
  249.                     sm_server:                     SMROOT/bin
  250.                     formatvol:                     SMROOT/bin
  251.                     shutserver:                    SMROOT/bin
  252.                     diskrw:                        SMROOT/bin
  253.                     producer/consumer example:  SMROOT/tests/producer_consumer
  254.  
  255.  
  256.                The tests that are included with the release refer
  257.                to binaries and libraries in the SMROOT/bin/,
  258.  
  259.  
  260.  
  261. Printed 11/9/93                                                 4
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. Installation(1)     UNIX Programmer's Manual      Installation(1)
  269.  
  270.  
  271.  
  272.                SMROOT/lib/, and SMROOT/include/ directories.
  273.                Once you have a working Storage Manager, you can
  274.                copy or move the contents of these directories to
  275.                their final destinations.
  276.  
  277.      Print     the documentation.  See the README in the
  278.                SMROOT/doc directory for instructions.
  279.  
  280.      Test      the binary versions of the Storage Manager.
  281.  
  282.                     cd SMROOT/tests
  283.                     more README
  284.  
  285.  
  286.                In SMROOT/tests are tests and example programs.
  287.                The README tells you how to run the tests.  If the
  288.                tests are successful, you are done.  If the
  289.                binaries you install do not work on your machine,
  290.                check the prerequisites, above.  If your system
  291.                meets all the prerequisites, you may want to try
  292.                making a Storage Manager from scratch.
  293.  
  294. COMPILING THE STORAGE MANAGER
  295.      As distributed, the makefiles will compile the entire system
  296.      with g++.  If wish to use E, remember to set the
  297.      SM_CLIENT_LIB environment variable to null (as described in
  298.      the installation instructions above), to avoid having E link
  299.      in its version of libsm_client.a.
  300.  
  301.      If you use a compiler other than g++, you must determine if
  302.      the compiler understands the keyword volatile. Synchroniza-
  303.      tion of the server processes uses the Silberschatz & Peter-
  304.      son algorithm #4 (p. 88, Operating System Concepts, Alter-
  305.      nate Edition, Addison-Wesley, 1988), which relies on the
  306.      volatile storage class.  There are two ways to make the few
  307.      files that implement the synchronization primitives.
  308.  
  309.      Volatile works
  310.                If your C++ compiler understands and properly han-
  311.                dles volatile, (or if it does not optimize away
  312.                the references to the volatile data, even if the
  313.                keyword volatile does not appear), and your C++
  314.                passes the keyword along to its underlying C com-
  315.                piler, the entire system can be made with C++
  316.                without changes to any source code.
  317.  
  318.      Volatile does not work
  319.                Your C++ compiler does not handle volatile, (it
  320.                optimizes the memory references away).  If your
  321.                machine has a test-and-set instruction
  322.                (e.g.,SPARC), an alternative synchronization algo-
  323.                rithm is used.  The system is compiled with C++
  324.  
  325.  
  326.  
  327. Printed 11/9/93                                                 5
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. Installation(1)     UNIX Programmer's Manual      Installation(1)
  335.  
  336.  
  337.  
  338.                and with -DTESTANDSET.  If you are porting the
  339.                Storage Manager to a new architecture, you will
  340.                have to write a test-and-set function (see
  341.                SMROOT/src/serverlib/disk/testandset.S).
  342.  
  343.      The determination is made by make(1) on the basis of the
  344.      macros CPLUSPLUS (found in SMROOT/makefile.options), HOST-
  345.      TYPE  (defined by make on some architectures) and CPUTYPE
  346.      (defined by make on other architectures).  You must not
  347.      redefine HOSTTYPE or CPUTYPE when you make a Storage
  348.      Manager.
  349.  
  350.      Be sure that your shell limits are high or unlimited (see
  351.      csh(1)).  To run build the Storage Manager, do
  352.  
  353.           cd SMROOT/src
  354.           make install
  355.  
  356.  
  357.      This will install the binaries in SMROOT/{bin,lib}.  More
  358.      information on making the Storage Manager is available in
  359.      SMROOT/doc/Makefiles.man.  Tests can then be run as
  360.      described above.
  361.  
  362. BROWSING THE STORAGE MANAGER SOURCE
  363.      The Storage Manager source is in SMROOT/src.  General infor-
  364.      mation on the Storage Manager source is available in
  365.      SMROOT/doc/source.man. Information on the Storage Manager's
  366.      architecture is available in SMROOT/doc/arch_overview.me.
  367.      If you wish to browse the source using tags you must first
  368.      make the tags files by running
  369.  
  370.           make tags
  371.  
  372.      in the SMROOT/src directory.  Also, put in your ~/.exrc the
  373.      following:
  374.  
  375.           set tags=./tags ./tags.all
  376.  
  377.  
  378.  
  379. SEE ALSO
  380.      Makefiles - making an Exodus Storage Manager
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393. Printed 11/9/93                                                 6
  394.  
  395.  
  396.  
  397.